Subject: Request for Review

From: "Chung-Huy Chen" <[email-masked]>
Date: Fri, 9 Apr 93 16:24:57 EDT

CPI-C NB SIG,

1) AD draft proposal available

  A copy of the AD draft proposal is now available via anonymous ftp
  on the /ciw/sig/nonblock library at ibmstandards.cary.ibm.com
  (192.35.236.4), including two files:

     ciw-nb.ps   :the main body of the proposal in postscript which
                  must be downloaded with the binary (or image) option
                  on.

     ciw-nb.fig  :figures referenced by ciw-nb.ps are in a plain text
                  format.

  This is the best solution that I can come up with so far such that
  figures are readable.  Please let me know if you have any trouble
  in printing the document.

2) Review plan

  4/9/93 - 4/19/93   :reviewed by NB SIG members
                      Please distribute your comments to the SIG as soon
                      as possible.

  4/20/93 - 5/3/93   :reviewed by all CIW members

  5/4/93             :request Approved Direction (AD)

3) Asynchronous notification (callback function) is incomplete
   ... please call back ...

  Addition of "asynchronous notification" is the primary change to the
  proposal distributed and discussed in the March meeting.  A preliminary
  design (still incomplete) is described in 'ciw-nb.ps' and several
  outstanding questions are also included in the paper for the reviewers.

  In case some people cannot access or print the document immediately,
  I repeat in the below a description of the asynchronous notification
  section and a description of the new call Set_Queue_Callback_Function.
  At the end, I post a few questions, I can think of, that are still
  outstanding.

 -------------------------
 Asynchronous notification

 An alternative to polling is to notify the program about the completion
 of an operation via some process-to-process communication mechanism
 (e.g., signal provided by some operating systems).  The
 notification occurs asynchronously because the program cannot
 predict when the notification will occur.  The program provides a
 function, called a callback function, that is called
 whenever an asynchronous notification occurs.  The callback function
 can do whatever the program wants to handle the condition.

 The program uses the Set_Queue_Callback_Function (CMSQCF) call to set
 a callback function and a user field for a conversation queue.  The
 program can choose not to use the user field by specifying a NULL
 (integer zero) value for the field.  The call also sets the
 processing mode of the queue to "nonblocking."  Once being set
 for a conversation queue, the callback function and user field can be
 applied to the subsequent outstanding operations on the queue until
 they are set differently or until the queue is closed (i.e., the
 conversation is ended).  The program does not have to set a callback
 function or a user field for each nonblocking call to the queue.

 The completion of an outstanding operation (i.e., the returned
 parameters are filled and the associated queue is set to "free")
 will trigger an asynchronous notification.  The notification interrupts
 execution of the program, passes the associated user field to the
 callback function set for the queue, and starts processing of the
 callback function in the execution environment of the interrupted
 program.  When the callback function returns,
 the program continues from where it was interrupted.

-------------------
 Implementation note

 Asynchronous notification and polling are two mutually exclusive
 mechanisms of allowing the program to accomplish the same goal (i.e., to
 synchronize with the completion of a call operation).  An implementation
 must support polling but may independently decide whether or not to
 support asynchronous notification.

 ------------------------------------
 Set_Queue_Callback_Function (CMSQCF)

 Set_Queue_Callback_Function (CMSQCF) is used to set a callback function
 and a user field for the identified queue and to set its processing mode
 to CM_NON_BLOCKING.

     conversation_ID  (input)
        Specifies the conversation identifier.

     conversation_queue  (input)
        Specifies the conversation queue on which completion of the
        call operation will invoke the callback function.  The
        conversation_queue can have one of the following values:

           -CM_SEND_QUEUE
           -CM_RECEIVE_QUEUE
           -CM_SEND_RECEIVE_QUEUE
           -CM_EXPEDITED_SEND_QUEUE
           -CM_EXPEDITED_RECEIVE_QUEUE

     callback_function  (input)
        Specifies a callback function to be set for the identified queue.

     user_field  (input)
        Specifies a user field to be associated with the identified queue.

     return_code  (output)
        Specifies the result of the call execution.
        The return_code variable can have one of the following values:
           -CM_OK
           -CM_PROGRAM_PARAMETER_CHECK
            This value indicates one of the following:
               --The conversation_ID contains an unassigned conversation
                 identifier.
               --The conversation_queue specifies an undefined value.
           -CM_NON_BLOCKING_LEVEL_MISMATCH
            This value indicates that the program has previously
            successfully issued Set_Processing_Mode (CMSPM) on the
            conversation.
           -CM_OPERATION_NOT_ACCEPTED
           -CM_PRODUCT_SPECIFIC_ERROR

 State Changes
    This call does not cause a state change.

 Usage Notes
   1. The call has an affinity to the queue specified in the
      conversation_queue parameter.

   2. The call sets the processing mode of the identified queue to
      CM_NON_BLOCKING.  The processing mode applies to all the
      subsequent calls to the queue until it is set to CM_BLOCKING
      using Set_Queue_Processing_Mode (CMSQPM) or until the
      conversation is ended.

   3. Once set for the identified queue, the callback function and
      user field will be associated with all the subsequent outstanding
      operations on the queue until they are set differently,
      Set_Queue_Processing_Mode (CMSQPM) is issued, or the conversation
      is ended.

   4. The program can specify a NULL (integer zero) value for the
      user_field parameter if it makes no use of the field.  Regardless
      of its value, the user field will be passed to the callback
      function when an outstanding operation completes on the queue.

 -------------------------
 Questions to SIG members:

    -How is the callback function used?
    -Is the user field sufficient for the callback function to work
     properly?  If so, how big should it be?
    -Is it allowed to make a CPI-C call within a callback function?
    -Can processing of a callback function be suspended because of
     another asynchronous notification (resulted from the completion
     of another CPI-C call)?

 Please contribute your ideas related to the above questions or any
 concerns you might have on the proposal to the SIG (i.e.,
 [email-masked]).

Chung-Huy Chen ([email-masked])
CIW NB SIG Coordinator